W2000A Screenshot Utility
=========================
--- Version 0.4 ---

Changelog
---------

* v0.1 (Initial Release):

  Provides new RS232 command # (pound) to initiate b/w screendump with simple
  RLE compression.  Usually only around 10-15kB to be transferred.

* v0.2:

  Additional ' (tick) command to initiate full plane dump with same simple RLE
  compression as with the # command.  Around 60-65kB total to be transferred.

  Planes are coloured and combined into an PPM image file.  Individual planes
  are also available as numbered PGM image files for inspection or partial
  export.

  New -h and -f command line options.  More status and progress messages on
  stderr.

  Since multiple planes can be output, data is written to file(s) in v0.2, no
  longer to stdout.  Use -f option to specify target file prefix.

* v0.3:

  Native windows support.  New command line option -c to specify COM port.
  Third party ComTools from Anton Zechner are used for now, likely to be
  replaced in upcoming releases.  Precompiled EXE is bundled from now on.

  Alternative BMP output instead of PPM/PGM.

  Makefile is provided.  Please note that we changed from .c to .cpp just for
  the third party ComTools, actual C++ features are not used.

  Patch is now included in BF1.2-0.80-beta upwards, so diff is no longer
  provided.  ' and # RS232 commands were removed, instead screenshots may be
  triggered in the Quick Print of the DSO.

* v0.4

  Linux: -c </dev/ttyXX> is implemented.

  Different RLE algorithm used (better compression for up to 60000 identical
  bytes.

  The program will now trigger a screenshot download (with -s), a monochrome
  screenshot (-m) or a dump of raw data (-d).

  The programm now keeps listening for as many dumps as you want to make.  Old
  behavior may be turned on by using -o (One-Shot).

  Because of that, files have to named sequentially.  A 4-digit number is
  starting at 0000 is added.  You may set the start point manually via -n.
  Please note:  Files are truncated and overwritten.  So make sure you
  move away your precious previously obtained scope data before a new
  invocation _or_ carefully use -n / -f.

  Monochromatic screenshots are now black/white, no longer black/greyish.

  New -i flag, inverts colours.  Especially useful for monochromatic
  screenshots.

  New command line option -t to specify trace file format, currently
  supported:  csv (default) and ascii.

  Patch is in SVN firmware and firmware starting FW1.2-0.84-beta.

* v0.88

  From now on, any version X.YY will work with version X.YY of the open source firmware 

* v0.89
  Modified order of planes

* v0.90
  Switch "-r" requests a dump of unfiltered data

  http://sourceforge.net/projects/welecw2000a/files/

* v0.91
  Switch "-v" display Version information

  http://sourceforge.net/projects/welecw2000a/files/

Known Issues
------------

  The BMP file format uses the somewhat uncommon storing order of
  "upside-down", in contrast to the usual raster scan order starting top-left
  (0, 0) and ending bottom-right (640, 480).

  Turns out that using the "normal" order is possible and specified by using a
  negative height value.  But after implementing this it further turns out
  that some programs and image libraries just don't expect that option to be
  used.

DSO Preperation
---------------

  * SVN firmware or firmware starting FW1.2-0.84-beta

  * Older firmware:
    Update firmware :)

Building
--------

  (not needed on Windows)

  $ make unix
  or
  $ make win

Making A Screenshot or Retrieving Traces
----------------------------------------

  Windows:

     Run w2000a-screenshot or edit and use provided .bat file.

  Advanced Usage:

  (1a) Start w2000a-screenshot:

       $ ./w2000a-screenshot -c $device

       The program now waits for data dumps from the DSO.

       (1a1) Use the Quick Print menu on the DSO.  Download starts
             automatically.

  (1b) Start w2000a-screenshot:

        $ ./w2000a-screenshot -c $device -s

       The program triggers a colour screenshot dump immediately,
       then exits.

       Use -m, -d for monochrome screenshot or traces respectively.

  (2a) In the case of screenshots, the utility decompresses the RLE data from
       the DSO to PGM files and colours and combines the retrieved planes to a
       single PPM image file.

       You might want to use ppmto*/pgmto*(1) of NetPBM or convert(1) of
       ImageMagick to make more handy files out of the PPM/PGM images, i.e.:
         $ convert screenshot-num.ppm screenshot-num.png

  (2b) For measurement data, the utility writes a .csv (Comma Seperated Values)
       file.  Use -t ascii to change to ASCII output (suitable for kst).
